home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_200 / 228_01 / cwindemo.doc < prev    next >
Text File  |  1987-07-29  |  25KB  |  658 lines
  1. C-window Demonstration     Copyright  (C) 1983 by c-systems
  2.  
  3.  
  4.  
  5.  
  6.              C-window Demonstration Document File
  7.              ------------------------------------
  8.  
  9.  
  10.  
  11. Do it NOW!
  12. ----------
  13.  
  14.       This file  shows how    to use    the c-window  DEMO provided in
  15.       Diskette B.
  16.  
  17.       Print this file and the file "dump.c" (also on Diskette  B),
  18.       as constant reference will be made to them in this document.
  19.  
  20. Overview
  21. --------
  22.  
  23.       C-window(tm) is used to debug C programs at the  source-code
  24.       level.   C-window   provides     an   interactive    debugging
  25.       environment that simplifies the program development process.
  26.  
  27.       C-window commands can:
  28.  
  29.           o  set  breakpoints  at  a  function  name and
  30.          source-code line,
  31.  
  32.           o  single   step     and   trace   at   the    C
  33.          source-statement level,
  34.  
  35.           o  display the value  of variables, using  the
  36.          same variable names as used in the C source
  37.          code (Local and external are supported),
  38.  
  39.           o  display  the  source  code  of  the program
  40.          under test,
  41.  
  42.           o  display complex expressions, like the third
  43.          element of an array of characters, which is
  44.          a  member  of    a  structure,  which  is  an
  45.          element in an array of structures, and
  46.  
  47.           o  override minor  program bugs  allowing more
  48.          of  the  program  to  be  tested  before  a
  49.          recompilation is needed.
  50.  
  51.  
  52.       To  use  the    c-window  debugger,  the  source  code must be
  53.       compiled using the "-w" option of the c-systems C  compiler.
  54.       During the link step the object code library,  c-window.lib,
  55.       is included,    which embeds  the c-window  executive into the
  56.       executable  object  file.  When  the    final  test  module is
  57.       invoked, the c-window  executive is actually    given control,
  58.       not the program being tested.
  59.  
  60. The Programs Dump.C and Dump.Exe
  61. --------------------------------
  62.  
  63.       Dump.c is the source code  for a dump utility that  dumps an
  64.       ASCII file in both hex. and ASCII format, while showing  the
  65.       address  of  the  data  in  the file. The executable module,
  66.       "dump.exe" is also contained on Diskette B.
  67.  
  68.       To study the output of this program, type:
  69.  
  70.  
  71.       A>dump dump.c
  72.  
  73.  
  74.       (For the purposes  of this DEMO  package we assume  that all
  75.       files mentioned are available on drive A.)
  76.  
  77.       The program reads the  input file dump.c and    displays three
  78.       fields  on  the  monitor.  The  leftmost  field contains the
  79.       starting address  of the  data displayed.  The middle  field
  80.       contains  the  hex.  representation  of  the    file,  and the
  81.       rightmost  field  contains  the  ASCII representation of the
  82.       hex. data. Periods are  displayed in the rightmost  field to
  83.       represent extended-ASCII characters.
  84.  
  85. C-window Demonstration Program
  86. ------------------------------
  87.  
  88.       I suggest that  you review the  "dump.c" source code  before
  89.       proceeding with this DEMO.
  90.  
  91.       The DEMO program,"cwdump.exe", is also contained on Diskette
  92.       B. Assuming it is on drive A, type
  93.  
  94.  
  95.    A>cwdump dump.c
  96.  
  97.  
  98.       to start the DEMO.
  99.  
  100.       If you  are using  an IBM-PC    or compatible,    the screen  is
  101.       divided into three sections.    These sections are treated  as
  102.       independent  windows    by  the  c-window  executive.  The top
  103.       window is  the debugger  interface. All  commands issued and
  104.       responses received are displayed within the top window.  The
  105.       middle window is dedicated to the application keyboard input
  106.       and screen output. The hex.  dump that you saw when  you ran
  107.       "dump.exe" will  appear only  within this  window. The  last
  108.       window, at  the bottom  of the  screen, displays  the source
  109.       code of the file being  debugged. Whenever a single step,  a
  110.       trace, or a breakpoint occurs the last window is updated  to
  111.       show    the  results  of  the  instruction.  This  allows  for
  112.       debugging at the  source level without  the need to  reprint
  113.       the source code each time a source code change is made.
  114.  
  115.       When    the  program  begins  execution  a  message  is issued
  116.       indicating the  function name  ("main") and  the line number
  117.       where execution begins. The message
  118.  
  119.  
  120.    entry at main line 22
  121.    >>
  122.  
  123.  
  124.       should appear in the    top window, showing that  execution of
  125.       the program under test started in the function named    "main"
  126.       at line 22. The ">>" is the c-window command-line prompt and
  127.       indicates that c-window is waiting for a command. C-window's
  128.       response to your command is not preceded by the ">>' prompt,
  129.       so you can easily tell them apart.
  130.  
  131.       To exit the DEMO, type "ex" after the ">>' prompt  displayed
  132.       in the top window.
  133.  
  134.       As  our  first  command  to  the debugger, let's display the
  135.       arguments passed  into the  "main" function  (i.e. argc  and
  136.       argv). The command
  137.  
  138.  
  139.    >>d argc
  140.    2
  141.  
  142.  
  143.       displays the number of parameters typed on the command  line
  144.       when the program was invoked. The "2" shown on the next line
  145.       is c-window's response to this command.
  146.  
  147.       To display the parameter entered on the command line, type:
  148.  
  149.  
  150.    >>ds argv[1]
  151.    dump.c
  152.  
  153.  
  154.       The <ds> command tells  c-window to display "argv[1]"  using
  155.       the string  format, and  indeed C-window's  response to  the
  156.       command  matches  the  command-line  entry  used  to    invoke
  157.       "cwdump.exe"
  158.  
  159.       We saw earlier  that "argc" was  equal to 2.  On line 22  of
  160.       "dump.c" an "if" statement checks  to see if "argc" is  less
  161.       than 2.  Since "argc"  is not  less than  2, we  expect that
  162.       lines 23, 24, and 25    (the body of the "if"  statement) will
  163.       be  skipped  and  execution  resumed    at  line 26, the first
  164.       statement after the  "if" statement. C-window`s  single step
  165.       command is used below. Let's see what happens.
  166.  
  167.  
  168.    >>s
  169.    step at main line 26
  170.  
  171.  
  172.       Sure enough. The body of the "if" statement was skipped  and
  173.       line 26 will be executed next.
  174.  
  175.       The "if" statement on line  26 tries to open the  file named
  176.       in argv[1] ("dump.c") and then checks the value returned  by
  177.       "fopen" to  see if  any errors  were detected.  Let's single
  178.       step again and look at the results.
  179.  
  180.  
  181.    >>s
  182.    step at main line 30
  183.  
  184.  
  185.       C-window's response shows that no errors were detected since
  186.       line 27 and  28 were skipped.  The pointer "infp"  now holds
  187.       the file pointer that will  be used for all subsequent  file
  188.       operations on "dump.c".
  189.  
  190.       The "if" statement on line 30 checks if an output file  name
  191.       was entered on the command line of "cwdump" and also  checks
  192.       that the output file is not the same file as the input file.
  193.  
  194.  
  195.    >>s
  196.    step at main line 37
  197.  
  198.  
  199.       As  no  output  file    was  typed  on    the  command line when
  200.       "cwdump.exe" was executed "argc"  is not greater than  2. So
  201.       lines 31, 32, and 33 were  skipped, and line 37 is the  next
  202.       line to  be executed.  Line 37  assigns the  console to  the
  203.       output file pointer so subsequent output done by the program
  204.       will go to the console screen.
  205.  
  206.       Now let's set a non-sticky breakpoint using the <g> command.
  207.       (go command).  This breakpoint  will be  set at  line 40  of
  208.       function "main". This line  follows the code that  reads the
  209.       first 16 bytes of "dump.c".
  210.  
  211.  
  212.    >>g main,40
  213.    break at main line 40
  214.  
  215.  
  216.       Execution begins at the current location and stops when line
  217.       40 in "main"  is to be  executed. C-window's response  shows
  218.       where  the  breakpoint  occurred.  The  number  of  elements
  219.       actually read from  the file, in  "nread", can be  displayed
  220.       using the command:
  221.  
  222.  
  223.    >>d nread
  224.    10
  225.  
  226.  
  227.       The <d> command indicates to display the variable "nread" in
  228.       hex. format  (Any C  expression can  be displayed,  not just
  229.       simple variables.) So "nread"  = 0x10 or 16  decimal. Notice
  230.       that you typed "nread", the same name declared in the source
  231.       code. This is symbolic debugging. The value of "nread" shows
  232.       that 16 bytes were read from "dump.c"
  233.  
  234.       Alternately, to display the contents of "nread" in  decimal,
  235.       use:
  236.  
  237.  
  238.    >>dd nread
  239.    16
  240.  
  241.  
  242.       Let's look at the data that was read from "dump.c". Since we
  243.       know that this  data was placed  into a buffer  with address
  244.       "buf", to  display the  data in  a byte-fo